=========================================================================== USER'S GUIDE to PCX KIT 5.0 Copyright (c) 1994 by Peter Donnelly Skookum Software 1301 Ryan Street Victoria BC Canada V8T 4Y8 --------------------------------------------------------------------------- CONTENTS -------- PCX Introduction Capabilities Using the modules References CLIP Introduction Operation Using CLIP images in Pascal and C/C++ Incorporating palette changes Linking data into the EXE file CLIPSHOW Introduction Examples --------------------------------------------------------------------------- PCX --- Introduction ------------ This is a set of modules to display .PCX files under DOS. The actual work of decoding the file and moving the data into video memory is done in assembler and is very fast. Versions are provided for Turbo/Borland Pascal and C++. Both use the same assembler modules (VGA.ASM and, in the registered version, SVGA.ASM). Compiled versions of these have been provided for those who do not have TASM. See comments in the files for instructions on how to compile them if you make changes. PCX.PAS will automatically link in VGAP.OBJ and SVGAP.OBJ when compiled to PCX.TPU. For C++, VGAC.OBJ and SVGAC.OBJ need to be added to the project like any other modules; the supplied versions are for the large memory model. Used to create the code were: Turbo Pascal for DOS version 6.0 Turbo C++ for DOS version 3.0 Turbo Assembler version 2.0 Capabilities ------------ The following display modes are supported for VGA cards: Mode Resolution Colors ~~~~ ~~~~~~~~~~ ~~~~~~ 0Dh 13d 320 x 200 16 0Eh 14d 640 x 200 16 10h 16d 640 x 350 16 12h 18d 640 x 480 16 13h 19d 320 x 200 256 The following modes are supported for Super-VGA cards with VESA BIOS: * 100h 256d 640 x 400 256 * 101h 257d 640 x 480 256 102h 258d 800 x 600 16 * 103h 259d 800 x 600 256 * 105h 261d 1024 x 768 256 * 107h 263d 1280 x 1024 256 [* Supported by registered version only.] The 256-color modes are not supported for PCX files with no palette information, i.e. those produced by versions of Paintbrush earlier than 3.0. Images wider than the screen cannot be displayed. Images taller than the screen are written to memory without checking to see whether they overrun the space available. Note that the video mode is set directly through BIOS, never with the BGI. If you want to use any BGI functions after the PCX file is displayed, you'll have to rewrite the mode-setting routines (for modes supported by the BGI) to use InitGraph and SetGraphMode. Using the modules ----------------- The sample implementations and the comments in the source code should make it clear how to use PCX in your own C++ and Pascal programs. Essentially all you have to do is pass the pathname of a PCX file to the C++ read_it() or Pascal ReadIt function along with a video mode and an options word. Mode ---- If the mode argument is zero (you can use the constant auto_set or, in Pascal, AutoSet), the program will determine the best mode based on the file's original resolution and the capabilities of the current video display. The image will be displayed at its original resolution unless it is too wide to fit on the screen, in which case the program will try to display it at a higher resolution. Options ------- The options argument is set by ORing the supplied constants; see the sample implementations, and the list of constants in the modules. The available options are horizontal and vertical centering, preserving video memory (conceivably of some use for simple animation effects or overlaying images, provided the palette does not change), and hiding the picture until it is completely written to video memory. In addition to read_it(), there are some other functions that may be of use in direct calls. These are listed in PCX.H and in the interface section of PCX.PAS. References ---------- Richard F. Ferraro, "Programmer's Guide to the EGA and VGA Cards" (Addison-Wesley, 1988). Richard Wilton, "Programmer's Guide to PC Video Systems" Second Edition (Microsoft Press, 1994). "Technical Reference Manual [for Paintbrush]" (Zsoft, 1988). The information in this booklet is also found in a file distributed with at least some versions of Microsoft/PC Paintbrush. Further information on programming for VESA-compliant Super-VGA cards can be obtained from: Video Electronics Standards Association 2150 North First St., Suite 440 San Jose CA 95131-2029 Phone (408) 435-0333 --------------------------------------------------------------------------- CLIP ---- Introduction ------------ The Borland Graphical Interface contains an easy-to-use procedure, PutImage (the PUTIMAGE function in C/C++), for displaying complex images on a portion of the screen. However, the Turbo/Borland C/C++ or Pascal programmer faces the difficulty of getting the image into a usable form in the first place - that is, of drawing it and then converting it into the format that PutImage requires. CLIP is a bridge between powerful commercial painting programs and the BGI. It lets you "clip" images of any size (up to the 64K limit imposed by PutImage) from PCX files in EGA and VGA medium or high resolution, and puts these images in files that can be used in your C or Pascal routines with a minimum of effort. Operation --------- The program is very simple to use. First create a screen-wide PCX graphics file in 16-color 640x350 or 640x480 resolution, using a painting or screen-capture program. (If your software doesn't directly support the PCX format, it may include a conversion program that does.) Then run CLIP with the pathname of the graphics file on the command line; don't include the ".PCX" part. By default the program will come up in 640x480 resolution if your system supports it, but you can override this default by entering "/e" on the command line after the PCX file name, in which case the display mode will be 640x350 and only EGA palette information will be produced (more on this below). Now, with the mouse, point to one corner of the image you wish to save. Hold down the left button and drag the mouse to create a frame around the image. The area you are defining includes the pixels covered by the frame lines, so that you can work right to the edge of the screen. When you release the button, you are prompted to enter a name for the image file. Type the file name and press , or abort with . You may use any file name except one with the extension ".PAL". If the image is too large for the BGI PutImage procedure, a bell sounds and you are not allowed to save. The size limit is about 58 percent of the screen in EGA mode or about 42 percent in VGA. If you want to save the entire screen, you can of course do so in chunks; but a better way is to use PCX.PAS or PCX.CPP to display the original PCX image in your program. By default the co-ordinates of the mouse are shown at the upper right corner of the screen. This information can be useful for cutting images exactly to size, especially if you have made a note of the desired boundaries while working in the magnified mode of your painting program. CLIP will ignore the display of co-ordinates when saving an image clipped from this part of the screen; however, you can toggle off the display with if you wish to see what lies beneath. Continue saving images from the screen until you're done; then press or to exit. Using CLIP images in Pascal and C/C++ ------------------------------------- The data structure used by Borland's image-manipulating procedures and functions is the same in both Pascal and C/C++, and CLIP's output files are equally usable with either language. The examples in this section will be in Pascal. The disk file created by CLIP to store an image takes exactly the same form as the data structure created by the GetImage procedure and used by PutImage. It is an untyped file. The first two words in the file store the width and height respectively of the image (counting from zero: an image of "1 by 1" is actually 2 by 2). The PutImage procedure uses these figures to set up the image properly, and they are also used by ImageSize to calculate the storage needed for the image. The BGI does not use data compression; a blank image occupies as much storage space as a complex image of the same dimensions. Here is a simple routine to import an image from a file and display it at the current pointer. var BitMap: Pointer; f: file; Begin Assign(f, 'MYIMAGE.IM'); Reset(f, 1); GetMem(BitMap, FileSize(f)); BlockRead(f, BitMap^, FileSize(f)); PutImage(GetX, GetY, BitMap^, CopyPut); End; For a program that uses multiple images, it may be convenient to group all the images together in a single data file. It is easy to do so with the DOS Copy command. For example, to create a file "CHESSMEN" containing all the pieces: COPY KING/B + QUEEN + BISHOP + KNIGHT + ROOK + PAWN CHESSMEN Note the "/B" argument after the first filename. Do not omit this; it is essential so that DOS treats all the files as binary and does not truncate any on encountering a Control-Z. Obviously it is up to the programmer to ensure that the file-reading routines take into account the number of bytes occupied by each image. If the file contains images of different sizes that are to be stored dynamically as they are imported, you can use the ImageSize function to determine how much memory to allocate for each image: var Width, Height, Size: word; BitMap: pointer; f: file; Begin Assign(f, 'IMAGES.DTA'); Reset(f, 1); Repeat BlockRead(f, Width, 2); { Get dimensions from header } BlockRead(f, Height, 2); Size:= ImageSize(0, 0, Width, Height); GetMem(BitMap, Size); Seek(f, FilePos(f) - 4); { Back up } BlockRead(f, Bitmap^, Size); { Get whole image } Until Eof(f); End; This routine has the great advantage that you can alter the size of any of the component images in the file without having to change program code. Incorporating palette changes ----------------------------- Whenever you save an image file, CLIP automatically creates a palette file with the same name and the extension ".PAL". If CLIP is running in EGA (350-line) mode, this is simply an untyped 17-byte file containing a PaletteType record. For the VGA, it is an array of the RGB values for each of the 16 palette entries, or 48 bytes in all. If you are working in 350-line mode on the VGA, the program presumes that you want only EGA palette data. If you want the full VGA information, you can load the file in 480-line mode; the resulting distortion will make no difference if the clipped images are ultimately to be displayed in their original 350-line format. For the EGA, you can easily import saved palette values into your own program by BlockReading the palette file into a PaletteType variable. It is then simply a matter of passing that variable into SetAllPalette. (Of course, in many cases it may be preferable to hard-code the palette values, which can be examined with DEBUG.) For the VGA, things are a bit more complicated. Here you have to make these declarations: type RGBrec = record redval, greenval, blueval: byte; end; var RGBpalette: array[0..15] of RGBrec; Now BlockRead the palette file into RGBpalette. From here the data can be passed into the BGI's SetRGBPalette procedure; but first you have to make sure that the palette entries are pointing to the registers you are modifying. (In the VGA, the 16 palette entries don't contain color values; they contain the numbers of color registers, which in turn hold the actual colors.) By default the palette points to registers 0-5, 20, 7, and 56-63, which contain the standard EGA colors. You can either modify these registers or else use SetPalette to put the numbers 0-15 in the palette, then modify registers 0-15 with SetRGBPalette. Linking data into the .EXE file ------------------------------- For the sake of tidiness you may want to incorporate image and palette data in the executable file itself rather than keeping it in separate files. Turbo/Borland Pascal makes this easy. Suppose you have an image of an apple in the file MYAPPLE.IM. First convert this to an object file with Borland's BINOBJ program thus: BINOBJ MYAPPLE.IM APPLE GETAPPLE There are three arguments on the command line. The first is the source file, the second is the destination file (.OBJ is assumed), and the third is the public declaration or interface of the object file. You are creating APPLE.OBJ, which contains the public declaration GetApple. Now, in your Pascal program, you declare a dummy "procedure" using the public name of the data, and link in the object file: procedure GetApple; external; {$L APPLE.OBJ} Finally, you declare a pointer variable and assign it the address of the dummy procedure: var AppleImage: pointer; AppleImage:= @GetApple; And when you want to display the image: PutImage(X, Y, AppleImage^, CopyPut); X and Y are the desired screen coordinates for the upper left corner of the image. Although linked data is convenient, remember that it takes up memory space for the life of the program, whereas data from files can be read into dynamic memory and discarded when no longer needed. If memory is in short supply and an image only has to be written to the screen once (for example, as part of a "title page"), a separate data file is probably the best choice. --------------------------------------------------------------------------- CLIPSHOW -------- Introduction ------------ This little program is for reviewing your collection of BGI clip art; that is, image files created with CLIP or a similar program and suited for use with the PutImage procedure/function in Turbo/Borland Pascal or C/C++. To run the program, enter a filespec on the command line. A directory path and the usual wildcards are accepted. Optionally you may specify a palette file as the second argument. It is assumed that this file is in the same directory as the image file(s); if you don't specify an extension, ".PAL" is appended. If you don't specify a palette at all, the program will attempt to match each image file with a ".PAL" file; for example, it will try to display "ROSE.IM" with the color data from a file called "ROSE.PAL". If there is no matching palette file, or if it is the wrong type for the present display mode, the default colors are used. (See CLIP.DOC for more information on palette files.) By default the program will run in VGA 640x480 resolution if your system supports it, or in EGA 640x350 otherwise. You can force it into EGA mode by entering "/e" on the command line as the last argument. Examples -------- C:>clipshow daisy The program will display "DAISY" from the current directory and will set the colors from "DAISY.PAL" if that palette file exists and is the right type for the default display mode. C:>clipshow \images\*.im blossoms /e The program will display all files in C:\IMAGES that have the extension ".IM", using the palette file "BLOSSOMS.PAL" from the same directory, and will run in EGA mode. The program looks for any BGI-format image files that match the filespec. To weed out non-image files, CLIPSHOW checks the file size against the image size calculated from the first two words in the file; so it will not read a file that has been appended to. To proceed to the next image, strike or . To quit the program, strike , , or . ===========================================================================